fix: skills reference swamp-troubleshooting for understanding internals#813
Merged
fix: skills reference swamp-troubleshooting for understanding internals#813
Conversation
stack72
force-pushed
the
skills-troubleshooting-reference
branch
4 times, most recently
from
6946034 to
c0d8c98
Compare
When CLI --help doesn't provide enough detail about swamp internals (auth
flow, extension push, init process), Claude had no guidance to dig deeper
into the source code. This updates all swamp skills to reference
swamp-troubleshooting as a fallback, and broadens swamp-troubleshooting
itself to cover "understanding internals" — not just error debugging.
Changes:
- Add "Understand swamp internals | swamp-troubleshooting" row to the
"When to Use Other Skills" table in all 10 swamp-* skills
- Broaden swamp-troubleshooting description to trigger on understanding
signals ("how does", "where is", "internals") not just error signals
- Add "When CLI Help Isn't Enough" section to swamp-troubleshooting with
specific areas: auth, extension push, init, data persistence
- Move verbose Model Outputs section from swamp-model SKILL.md to
references/outputs.md to stay under 500-line skill-creator limit
(580 → 495 lines)
- Register outputs.md in skill_assets.ts for repo init/upgrade
Closes #804
Co-authored-by: Blake Irvin <blakeirvin@me.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
stack72
force-pushed
the
skills-troubleshooting-reference
branch
from
c0d8c98 to
bdd9fe9
Compare
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Adversarial Review
This PR is almost entirely documentation restructuring (skill markdown files) with one code change: adding two entries to the BUNDLED_SKILLS array in src/infrastructure/assets/skill_assets.ts.
Critical / High
None.
Medium
None.
Low
.claude/skills/swamp-data/SKILL.md:368 — The GC dry-run output shape example was trimmed from two items to one. The removed item showed a differentreasonvalue ("lifetime:1h") which demonstrated that multiple reason formats exist. Minor documentation loss — users seeing only"lifetime:ephemeral"might not realize duration-based reasons also appear. Not a code issue.
Verdict
PASS — This is a straightforward documentation refactor: content moved from inline SKILL.md sections to references/ files, cross-skill troubleshooting links added, and the two new reference files registered in skill_assets.ts. The code change is a static array append with no logic. All referenced files exist on disk. No correctness, security, or resource management concerns.
There was a problem hiding this comment.
Review: Approve
No blocking issues found. This is a well-structured documentation improvement.
What was reviewed
- All 13 skill markdown files for consistent troubleshooting cross-references
- New reference files (
outputs.md,checks.md) for content accuracy vs originals skill_assets.tsregistration entries follow existing patternsswamp-model/SKILL.mdis 495 lines (under the 500-line skill-creator limit)swamp-troubleshootingdescription correctly broadened for understanding signals
Observations
- Content in the extracted reference files is a faithful move — no information lost
- The
swamp-data/SKILL.mdchanges go beyond just adding the troubleshooting row — the rename workflow and GC sections were improved with step-by-step workflows and safety guidance, which is a nice improvement - All "When to Use Other Skills" tables are consistently formatted across skills
- No code logic changes, no security concerns, no test changes needed
Looks good to merge.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
swamp-troubleshootingin their "When to Use Other Skills" table, so Claude knows to fetch source code when CLI--helpdoesn't provide enough detail about internals (auth flow, extension push, init process, etc.)swamp-troubleshootingscope beyond just error debugging — it now triggers on understanding signals ("how does", "where is", "internals") and includes a new "When CLI Help Isn't Enough" section with specific areas to investigateswamp-model/SKILL.mdtoreferences/outputs.mdto stay under the 500-line skill-creator limit (580 → 495 lines)outputs.mdinskill_assets.tsso it's included inrepo initandrepo upgradeCloses #804
Test plan
deno checkpasses onskill_assets.tsswamp-troubleshooting/SKILL.mddescription includes understanding signalsswamp-model/SKILL.mdis under 500 linesreferences/outputs.mdcontains the moved contentrepo initandrepo upgradecopy the newoutputs.mdfile🤖 Generated with Claude Code
Co-authored-by: Blake Irvin blakeirvin@me.com